﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>Entities</title>
<link href="bootstrap.min.css" type="text/css" rel="stylesheet" />
</head>

<body>

<ul>
	<li><a href="#DocEntityClasses">Entity classes</a></li>
	<li><a href="#DocConventionalInterfaces">Conventional interfaces</a><ul>
		<li><a href="#DocAuditing">Auditing</a></li>
		<li><a href="#DocSoftDelete">Soft delete</a></li>
		<li><a href="#DocActivePassive">Active/Passive</a></li>
	</ul>
	</li>
	<li><a href="#DocIEntityInterfaces">IEntity interfaces</a></li>
</ul>
<p>Entities are one of the core concepts of DDD (Domain Driven Design). Eric Evans describe it as "<em>An object that is not fundamentally defined by its attributes, but rather by a thread of continuity and identity</em>". So, entities have Id's and stored in a database. 
An entity is generally mapped to a table in the database.</p>
<h3 id="DocEntityClasses">Entity classes</h3>
<p>In ASP.NET Boilerplate, Entities are derived from <strong>Entity </strong>
class. See the sample below:</p>

<pre lang="cs">public class Person : Entity
{
    public virtual string Name { get; set; }

    public virtual DateTime CreationTime { get; set; }

    public Task()
    {
        CreationTime = DateTime.Now;
    }
}</pre>

<p><strong>Person</strong> class is defined as an entity. It has two properties. 
Also, Entity class defines an <strong>Id</strong> property. It's <strong>primary 
key </strong>of the Entity. So, name of primary keys of all Entities are same, 
it's <strong>Id</strong>.</p>
<p>Type of Id (primary key) can be changed. It's
<strong>int </strong>(Int32) by default. If you want to define another 
type as Id, you should explicitly declare it as shown below:</p>

<pre lang="cs">public class Person : Entity&lt;long&gt;
{
    public virtual string Name { get; set; }

    public virtual DateTime CreationTime { get; set; }

    public Task()
    {
        CreationTime = DateTime.Now;
    }
}</pre>

<p>Also, you can set it as string, Guid or something else.</p>
<p>Entity class overrides <strong>equality</strong> operator (==) to easily 
check if two entities are equal (their Id is equal). It also defines the <strong>
IsTransient()</strong> method to check if it has an Id or not.</p>
<h3 id="DocConventionalInterfaces">Conventional interfaces</h3>
<p>In many application, similar entity properties (and database table fields) 
are used like CreationTime indicates that when this entity is created. ASP.NET 
Boilerplate provides some useful interfaces to make this common properties 
explicit and expressive. Also, this provides a way of coding common code for 
Entities which implement these interfaces.</p>
<h4 id="DocAuditing">Auditing</h4>
<p><strong>IHasCreationTime</strong> makes it possible to use a common property 
for '<strong>creation time</strong>' information of an entity. ASP.NET Boilerplate automatically sets 
CreationTime to <strong>current time</strong> when an Entity is inserted 
into database which implements this interface.</p>
<pre lang="cs">public interface IHasCreationTime
{
   <span lang="tr"> </span>DateTime CreationTime { get; set; }
}</pre>
<p>Person class can be re-written as shown below by implementing IHasCreationTime interface:</p>
<pre lang="cs">public class Person : Entity&lt;long&gt;, IHasCreationTime
{
    public virtual string Name { get; set; }

    public virtual DateTime CreationTime { get; set; }

    public Task()
    {
        CreationTime = DateTime.Now;
    }
}</pre>

<p><strong>ICreationAudited</strong> extens IHasCreationTime by adding&nbsp; 
<strong>CreatorUserId</strong>:</p>
<pre lang="cs">public interface ICreationAudited : IHasCreationTime
{
<span lang="tr">    long</span>? CreatorUserId { get; set; }
}</pre>
<p>ASP.NET Boilerplate automatically sets CreatorUserId to <strong>current 
user's id</strong> when saving a new entity.</p>
<p>You can also implement ICreationAudited easily by deriving your entity from
<strong>CreationAuditedEntity</strong> class. It has also a generic version for 
different type of Id properties.</p>
<p>There is also similar interface for modifications:</p>
<pre lang="cs">public interface IModificationAudited
{
    DateTime? LastModificationTime { get; set; }

    <span lang="tr">long</span>? LastModifierUserId { get; set; }
}</pre>
<p>ASP.NET Boilerplate also automatically sets these properties when updating an 
entity. You just define them for your entity.</p>
<p>If you want to implement all of audit properties, you can direcly implement
<strong>IAudited </strong>interface:</p>
<pre lang="cs">public interface IAudited : ICreationAudited, IModificationAudited
{
        
}</pre>
<p>As a shortcut, you can derive from <strong>AuditedEntity </strong>class 
instead of direcly implementing <strong>IAudited</strong>. AuditedEntity class has 
also a generic version for different type of Id properties.</p>
<h4 id="DocSoftDelete">Soft delete</h4>
<p>Soft delete is a commonly used pattern to mark an Entity as deleted instead 
of actually deleting it from database. For instace, you may not want to hard 
delete a User from database since it has many releations to other tables. 
<strong>ISoftDelete</strong> interface is used for this purpose:</p>
<pre lang="cs">public interface ISoftDelete
{
    bool IsDeleted { get; set; }
}</pre>
<p>ASP.NET Boilerplate implements soft delete pattern out-of-the-box. When a 
soft-delete entity is being deleted, ASP.NET Boilerplate detects this, prevents 
deleting, sets IsDeleted as true and updates entity in the database. Also, it 
does not retrive (select) soft deleted entities from database, automatically 
filters them.</p>
<p>If you use soft delete, you may also want to store information when an entity 
is deleted and who deleted it. You can implement <strong>IDeletionAudited</strong> interface that is shown below:</p>
<pre lang="cs">public interface IDeletionAudited : ISoftDelete
{
    long? DeleterUserId { get; set; }

    DateTime? DeletionTime { get; set; }
}
</pre>
<p>IDeletionAudited extends ISoftDelete as you noticed. ASP.NET Boilerplate 
automatically sets these properties when an entity is deleted.</p>
<p>If you want to implement all audit interfaces (creation, modification and 
deletion) for an entity, you can directly implement <strong>IFullAudited</strong> 
since it inherits all:</p>
<pre lang="cs">public interface IFullAudited : IAudited, IDeletionAudited
{
        
}</pre>
<p>&nbsp;As a shortcut, you can derive your entity from <strong>
FullAuditedEntity</strong> class that implements all.</p>
<p>NOTE: All audit interfaces and classes have a generic version for defining navigation property 
to your <strong>User</strong> entity (like ICreationAudited&lt;TUser&gt; and 
FullAuditedEntity&lt;TPrimaryKey, TUser&gt;).&nbsp;</p>
<h4 id="DocActivePassive">Active/Passive</h4>
<p>Some entities need to be marked as Active or Passive. Then you may take 
action upon active/passive state of the entity. You can implement <strong>
IPassivable</strong> interface that is created for this reason. It defines
<strong>IsActive</strong> property.</p>
<p>If your entity will be active on first creation, you can set IsActive to true 
in the constructor.</p>
<p>This is different than soft delete (IsDeleted). If an entity is soft deleted, 
it can not be retrieved from database (ABP prevents it as default). But, for 
active/passive entities, it's completely up to you to control getting entities.</p>
<h3 id="DocIEntityInterfaces">IEntity interfaces</h3>
<p>Actually, <strong>Entity </strong>class implements <strong>IEntity </strong>interface (and <strong>Entity&lt;TPrimaryKey&gt;</strong> implements <strong>IEntity&lt;TPrimaryKey&gt;</strong>). 
If you do not want to derive from Entity class, you can implement these 
interfaces directly. There are also corresponding interfaces for other entity 
classes. But this is not the suggested way, unless you have a good 
reason to do not derive from Entity classes.</p>

</body>

</html>
